---

Inside Macintosh: QuickTime Components

Previous | Overview | Contents | Next |

SGSetChannelUsage

The SGSetChannelUsage function specifies how a channel is to be used by the sequence grabber component. The sequence grabber component does not use a channel until you specify how it is to be used. You can specify that a channel is to be used for recording or previewing, or both. In addition, you can control whether the data captured by a channel is displayed during the record or preview operation.

pascal ComponentResult SGSetChannelUsage (SGChannel c,
                                         long usage);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

usage

Contains flags (defined by the SeqGrabUsageEnum data type) specifying how the channel is to be used. You may set more than one of these flags to 1. Set unused flags to 0. The following flags are defined:

seqGrabRecord

Indicates that the channel is to be used during record operations. Set this flag to 1 to use a channel for recording.

seqGrabPreview

Indicates that the channel is to be used during preview operations. Set this flag to 1 to use a channel for previewing.

seqGrabPlayDuringRecord

Indicates that the sequence grabber may play the data captured by this channel during a record operation. If you set this flag to 1, the data from the channel may be played during the record operation, if the destination buffer is onscreen. Video data is displayed; sound data is played through the computer's speaker. However, playing the data may affect the quality of the recorded sequence by causing frames to be dropped. Set this flag to 0 to prevent the channel's data from being played during a record operation.

SGGetChannelUsage

The SGGetChannelUsage function allows you to determine how a channel is to be used by the sequence grabber component.

pascal ComponentResult SGGetChannelUsage (SGChannel c,
                                         long *usage);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

usage

Contains a pointer to flags indicating how the channel is to be used. More than one flag may be set to 1; unused flags are set to 0. The following flags are defined:

seqGrabRecord

Indicates that the channel is used during record operations.

seqGrabPreview

Indicates that the channel is used during preview operations.

seqGrabPlayDuringRecord

Indicates that the sequence grabber component plays the data captured by this channel during a record operation.

SGGetChannelInfo

The SGGetChannelInfo function allows you to determine how a channel's data is represented to the user--as visual or audio data, or both.

pascal ComponentResult SGGetChannelInfo (SGChannel c,
                                         long *channelInfo);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

channelInfo

Contains a pointer to a long integer that is to receive channel information flags. More than one flag may be set to 1. Unused flags are set to 0. The following flags are defined:

seqGrabHasBounds

Indicates that the channel has a visual representation. If this flag is set to 1, the channel has a visual representation.

seqGrabHasVolume

Indicates that the channel has an audio representation. If this flag is set to 1, the channel has an audio representation.

seqGrabHasDiscreteSamples

Indicates that the channel data is organized into discrete frames. If this flag is set to 1, you can use the SGSetChannelMaxFrames function (see SGSetChannelMaxFrames ) to limit the number of frames processed in a record operation or the rate at which those frames are processed. If this flag is set to 0, the channel data is not organized into frames. Therefore, you can only limit a record operation by setting the maximum time for the operation.

SGSetChannelPlayFlags

The SGSetChannelPlayFlags function allows you to influence the speed and quality with which the sequence grabber displays data from a channel.

pascal ComponentResult SGSetChannelPlayFlags (SGChannel c,
                                          long playFlags);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

playFlags

Specifies a long integer that contains flags that influence channel playback. The following values are defined--you must use one of these values:

channelPlayNormal

Instructs the channel component to use its default playback methodology.

channelPlayFast

Instructs the channel component to sacrifice playback quality in order to achieve the specified playback rate.

channelPlayHighQuality

Instructs the channel component to play the channel's data at the highest possible quality--this option sacrifices playback rate for the sake of image quality. This option may reduce the amount of processor time available for recording. This option does not affect the quality of the recorded data, however.

The following flag is defined--you may use this flag with any of the values defined for this parameter (set unused flags to 0):

channelPlayAllData

Instructs the channel component to try to play all of the data it captures, even the data that is stored in offscreen buffers. This option is useful when you want to be sure that the user sees as much of the captured data as possible. Set this flag to 1 to play all the captured data. You may combine this flag with any of the values defined for the playFlags parameter.

SGGetChannelPlayFlags

The SGGetChannelPlayFlags function allows you to retrieve the playback control flags that you set with the SGSetChannelPlayFlags function, which is described in the previous section.

pascal ComponentResult SGGetChannelPlayFlags (SGChannel c,
                                          long *playFlags);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

playFlags

Contains a pointer to a long integer that is to receive flags that influence channel playback. The following values are defined:

channelPlayNormal

The channel component uses its default playback methodology.

channelPlayFast

The channel component sacrifices playback quality in order to achieve the specified playback rate.

channelPlayHighQuality

The channel component plays the channel's data at the highest possible quality--this option sacrifices playback rate for the sake of image quality. This option may reduce the amount of processor time available for recording. This option does not affect the quality of the recorded data, however.

The following flag is defined and may be used with any of the values defined for this parameter (unused flags are set to 0):

channelPlayAllData

The channel component tries to play all of the data it captures, even the data that is stored in offscreen buffers. This option is useful when you want to be sure that the user sees as much of the captured data as possible.

SGSetChannelMaxFrames

The SGSetChannelMaxFrames function allows you to limit the number of frames that the sequence grabber will capture from a specified channel. This function works only with channels that have data that is organized into frames, such as video data from a video disc.

pascal ComponentResult SGSetChannelMaxFrames (SGChannel c,
                                          long frameCount);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

frameCount

Specifies the maximum number of frames to capture during the preview or record operation. Set this value to -1 to remove the limit.

SGGetChannelMaxFrames

The SGGetChannelMaxFrames function allows you to determine the number of frames left to be captured from a specified channel.

pascal ComponentResult SGGetChannelMaxFrames (SGChannel c,
                                          long *frameCount);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

frameCount

Contains a pointer to a long integer that is to receive a value specifying the number of frames left to be captured during the preview or record operation. If the returned value is -1, the sequence grabber captures as many frames as it can.

SGSetChannelBounds

The SGSetChannelBounds function allows you to specify a channel's display boundary rectangle. This rectangle defines the destination for data from this channel. This rectangle is defined in the graphics world you establish by calling the SGSetGWorld function, described on SGSetGWorld .

pascal ComponentResult SGSetChannelBounds (SGChannel c,
                                          const Rect *bounds);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

bounds

Contains a pointer to a rectangle that defines the channel's display boundary rectangle. This rectangle is defined in the graphics world you establish when you call the SGSetGWorld function, described on SGSetGWorld .

SGGetChannelBounds

The SGGetChannelBounds function allows you to determine a channel's display boundary rectangle.

pascal ComponentResult SGGetChannelBounds (SGChannel c,
                                          Rect *bounds);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

bounds

Contains a pointer to a rectangle structure that is to receive information about the channel's display boundary rectangle. This rectangle is defined in the graphics world that you establish when you call the SGSetGWorld function.

SGSetChannelVolume

The SGSetChannelVolume function sets a channel's sound volume.

pascal ComponentResult SGSetChannelVolume (SGChannel c,
                                          short volume);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

volume

Specifies the volume setting of the channel represented as a 16-bit, fixed-point number. The high-order 8 bits contain the integer part of the value; the low-order 8 bits contain the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.

SGGetChannelVolume

The SGGetChannelVolume function allows you to determine a channel's sound volume setting.

pascal ComponentResult SGGetChannelVolume (SGChannel c,
                                          short *volume);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

volume

Contains a pointer to an integer that is to receive the volume setting of the channel represented as a 16-bit, fixed-point number. The high-order 8 bits contain the integer part of the value; the low-order 8 bits contain the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.

SGSetChannelRefCon

The SGSetChannelRefCon function allows you to set the value of a reference constant that is passed to your callback functions (see "Video Channel Callback Functions," for information about the callback functions that are supported by video channels).

pascal ComponentResult SGSetChannelRefCon (SGChannel c,
                                          long refCon);


c

Specifies the reference that identifies the channel for this operation. You obtain this reference from the SGNewChannel function, described on SGNewChannel .

refCon

Specifies a reference constant value that is to be passed to your callback functions for this channel. See "Video Channel Callback Functions" for information about the callback functions that are supported by video channels. Sound channels do not support callback functions.

SGGetChannelSampleDescription

The SGGetChannelSampleDescription function allows you to retrieve a channel's sample description.

pascal ComponentResult SGGetChannelSampleDescription
                                         (SGChannel c, Handle sampleDesc);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, described on SGNewChannel and SGNewChannelFromComponent , respectively.

sampleDesc

Specifies a handle that is to receive the sample description.

SGGetChannelTimeScale

The SGGetChannelTimeScale function allows you to retrieve a channel's time scale.

pascal ComponentResult SGGetChannelTimeScale (SGChannel c,
                                          TimeScale *scale);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function; these functions are described on SGNewChannel and SGNewChannelFromComponent , respectively.

scale

Contains a pointer to a time scale structure. The channel component places information about its time scale into this structure.

SGSetChannelClip

The SGSetChannelClip function allows you to set a channel's clipping region.

pascal ComponentResult SGSetChannelClip (SGChannel c,
                                          RgnHandle theClip);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, described on SGNewChannel and SGNewChannelFromComponent , respectively.

theClip

Contains a handle to the new clipping region. Set this parameter to nil to remove the current clipping region. The channel component makes a copy of this handle; it is your application's responsibility to dispose of this handle when you are finished with it.

SGGetChannelClip

The SGGetChannelClip function allows you to retrieve a channel's clipping region.

pascal ComponentResult SGGetChannelClip (SGChannel c,
                                         RgnHandle *theClip);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, described on SGNewChannel and SGNewChannelFromComponent , respectively.

theClip

Contains a pointer to a handle that is to receive the clipping region. Your application is responsible for disposing of this handle. If there is no clipping region, the channel component sets this handle to nil .

Note
Some devices may not support clipping.

SGSetChannelMatrix

The SGSetChannelMatrix function allows you to set a channel's display transformation matrix.

pascal ComponentResult SGSetChannelMatrix (SGChannel c,
                                         const MatrixRecord *m);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, discussed on SGNewChannel and SGNewChannelFromComponent , respectively.

m

Contains a pointer to a matrix structure, as defined by the Movie Toolbox (see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information about matrix structures). Set this parameter to nil to select the identity matrix.

SGGetChannelMatrix

The SGGetChannelMatrix function allows you to retrieve a channel's display transformation matrix.

pascal ComponentResult SGGetChannelMatrix (SGChannel c,
                                          MatrixRecord *m);


c

Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, described on SGNewChannel and SGNewChannelFromComponent , respectively.

m

Contains a pointer to a matrix structure, as defined by the Movie Toolbox (see "Movie Toolbox" in Inside Macintosh: QuickTime for more information about matrix structures). The channel component places its current matrix values into this matrix structure.